Python SDK使用指南

本指南将会为您介绍如何使用Python SDK接入您的项目。如果您想获得API接口的详细说明，可以查看Python SDK API文档。您可以在访问GitHub获取Python SDK的源代码。

最新版本为：1.2.0

更新时间为：2019-09-24

注意，1.1.17版本在数据上报机制及稳定性上进行了重大优化，建议使用低版本的用户更新至最新版本。

升级命令：

pip install --upgrade ThinkingDataSdk

1. 初始化SDK

1.通过pip获取Python SDK

pip install ThinkingDataSdk

2.初始化SDK

请在程序初始化代码中引入SDK，并初始化获得SDK实例

from tgasdk import *

'''
也可以单独引入所需的类
from tgasdk import TGAException, TGAnalytics, DebugConsumer, BatchConsumer, AsyncBatchConsumer, LoggingConsumer, ROTATE_MODE
'''

# 初始化SDK
tga = TGAnalytics(LoggingConsumer("/path/to/log"))

您可以通过四种方法获得SDK实例，Consumer的具体差异，可查看API文档：

(1)LoggingConsumer：批量实时写本地文件，文件以天为分隔，需要与LogBus搭配使用进行数据上传，建议使用

tga = TGAnalytics(LoggingConsumer(PREFIX))

传入的参数为写入本地的文件夹地址，您只需将LogBus的监听文件夹地址设置为此处的地址，即可使用LogBus进行数据的监听上传。

(2)BatchConsumer：批量实时地向TA服务器传输数据（同步阻塞），不需要搭配传输工具，不建议在生产环境中使用

tga = TGAnalytics(BatchConsumer(SERVER_URI,APP_ID))

SERVER_URI为传输数据的URL，APP_ID为您的项目的APP ID

如果您使用的是云服务，请输入以下URL:

http://receiver.ta.thinkingdata.cn/logagent

如果您使用的是私有化部署的版本，请输入以下URL:

http://数据采集地址/logagent

(3)AsyncBatchConsumer：批量实时地向TA服务器传输数据（异步非阻塞），不需要搭配传输工具，不建议在生产环境中使用

tga = TGAnalytics(AsyncBatchConsumer(SERVER_URI,APP_ID,flush_size=200,queue_size=100000))

SERVER_URI为传输数据的URL，APP_ID为您的项目的APP ID

如果您使用的是云服务，请输入以下URL:

http://receiver.ta.thinkingdata.cn/logagent

如果您使用的是私有化部署的版本，请输入以下URL:

http://数据采集地址/logagent

flush_size为队列缓存的阈值，超过此值将立即进行发送。

queue_size为缓存队列的大小，超过queue_size的数据将会丢失。

(4)DebugConsumer：逐条实时地向TA服务器传输数据，不需要搭配传输工具，如果数据出现错误，整条数据都将不会入库，并且返回详细的错误说明，不建议在生产环境中使用

tga = TGAnalytics(DebugConsumer(SERVER_URI, APP_ID))

SERVER_URI为传输数据的URL，APP_ID为您的项目的APP ID

如果您使用的是云服务，请输入以下URL:

http://receiver.ta.thinkingdata.cn/logagent

如果您使用的是私有化部署的版本，请输入以下URL:

http://数据采集地址/logagent

2. 发送事件

在SDK初始化完成之后，您就可以调用track来上传事件，一般情况下，您可能需要上传十几到上百个不同的事件，如果您是第一次使用TDA后台，我们推荐您先上传几个关键事件。

如果您对需要发送什么样的事件有疑惑，可以查看快速使用指南了解更多信息。

a) 发送事件

您可以调用track来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，此处以用户付费作为范例：

distinct_id = "ABCDEF123456"

account_id = "TA10001"

properties = {
    "#time":datetime.datetime.now(),
    # 设置这条event发生的时间，如果不设置的话，则默认是当前时间

    "#ip":"192.168.1.1",
    # 设置用户的IP，tda会自动根据该IP解析省份、城市

    "Product_Name":"商品名",
    "Price":30,
    "OrderId":"订单号abc_123"
}

# 上传事件，包含账号ID与访客ID
ta.track(distinct_id,account_id,"Payment",properties)

# 您也可以只上传访客ID
# ta.track(distinct_id = distinct_id, event_name = "Payment", properties = properties)
# 或者只上传账号ID
# ta.track(account_id = account_id, event_name = "Payment", properties = properties)

注：为了保证访客ID与账号ID能够顺利进行绑定，如果您的游戏中会用到访客ID与账号ID，我们极力建议您同时上传这两个ID，否则将会出现账号无法匹配的情况，导致用户重复计算，具体的ID绑定规则可参考用户识别规则一章。

• 事件的名称只能以字母开头，可包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
• 事件的属性是一个dict对象，其中每个元素代表一个属性。
• Key的值为属性的名称，为str类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
• Value为该属性的值，支持str、int、float、bool、datetime.datetime、datetime.date

b) 设置公共事件属性

对于一些需要出现在所有事件中的属性属性，您可以调用set_super_properties来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。

# 设置公共事件属性
super_properties = {
    "server_version":"1.2.3",
    "server_name":"A1001"
}
ta.set_super_properties(super_properties)

distinct_id = "ABCDEF123456"
account_id = "TA10001"
properties = {
    "Product_Name":"商品A",
    "Price":60
}

# 上传事件，事件中将会带有公共事件属性以及该事件本身的属性
ta.track(distinct_id,account_id,"Payment",properties)

'''
相当于进行下列操作
properties = {
    "server_version":"1.2.3",
    "server_name":"A1001",
    "Product_Name":"商品A",
    "Price":60
}
ta.track(distinct_id,account_id,"Payment",properties)
'''

• 公共事件属性同样也是一个dict对象，其中每个元素代表一个属性。
• Key的值为属性的名称，为str类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
• Value为该属性的值，支持str、int、float、bool、datetime.datetime、datetime.date

如果调用set_super_properties设置先前已设置过的公共事件属性，则会覆盖之前的属性值。如果公共事件属性和track上传事件中的某个属性的Key重复，则该事件的属性会覆盖公共事件属性：

super_properties = {
    "server_version":"1.2.3",
    "server_name":"A1001"
}
ta.set_super_properties(super_properties)

super_properties = {"server_name":"B9999"}

ta.set_super_properties(super_properties)
# 此时"server"的值变为"B9999"

distinct_id = "ABCDEF123456"
account_id = "TA10001"
properties = {
    # 覆盖"server_version"
    "server_version":"1.3.4",      
    "Product_Name":"商品A",
    "Price":60
}

# 上传事件，此时"server_version"的值为"1.3.4","server_name"的值为"B9999"
ta.track(distinct_id,account_id,"Payment",properties)

如果您想要清空所有公共事件属性，可以调用clear_super_properties。

3. 用户属性

TA平台目前支持的用户属性设置接口为user_set、user_setOnce、user_add、user_del。

a) user_set

对于一般的用户属性，您可以调用user_set来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致：

properties = {"user_name":"ABC"}
# 上传用户属性，"user_name"的值为"ABC"
ta.user_set(account_id = account_id, distinct_id = distinct_id, properties = properties)

properties = {"user_name":"XYZ"}
# 再次上传用户属性，此时"user_name"的值会被覆盖为"XYZ"
ta.user_set(account_id = account_id, distinct_id = distinct_id, properties = properties)

• user_set设置的用户属性是一个dict对象，其中每个元素代表一个属性。
• Key的值为属性的名称，为str类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
• Value为该属性的值，支持str、int、float、bool、datetime.datetime、datetime.date

b) user_setOnce

如果您要上传的用户属性只要设置一次，则可以调用user_setOnce来进行设置，当该属性之前已经有值的时候，将会忽略这条信息：

properties = {"user_name":"ABC"}
# 上传用户属性，"user_name"的值为"ABC"
ta.user_setOnce(account_id = account_id, distinct_id = distinct_id, properties = properties)

properties = {
    "user_name":"XYZ",
    "user_age":18
    }
# 再次上传用户属性，此时"user_name"已存在值，因此不进行修改，仍为"ABC"；"user_age"的值为18
ta.user_setOnce(account_id = account_id, distinct_id = distinct_id, properties = properties)

user_setOnce设置的用户属性类型及限制条件与user_set一致。

c) user_add

当您要上传数值型的属性时，您可以调用user_add来对该属性进行累加操作，如果该属性还未被设置，则会赋值0后再进行计算，可传入负值，等同于相减操作。

properties = {
    "total_revenue":30,
    "vip_level":1
}
# 上传用户属性，此时"total_revenue"的值为30,"vip_level"的值为1
ta.user_add(account_id = account_id, distinct_id = distinct_id, properties = properties)

properties = {"total_revenue":60}
# 上传用户属性，此时"total_revenue"的值为90,"vip_level"的值为1
ta.user_add(account_id = account_id, distinct_id = distinct_id, properties = properties)

user_add设置的用户属性类型及限制条件与user_set一致，但只对数值型的用户属性有效。

d) user_del

如果您要删除某个用户，可以调用user_del将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

ta.user_del(account_id = account_id, distinct_id = distinct_id)

4. 其他操作

a) 立即提交数据

ta.flush()

立即提交数据到相应的接收器

b) 关闭sdk

ta.close()

关闭并退出sdk，请在关闭服务器前调用本接口，以避免缓存内的数据丢失

5. 相关预置属性

5.1 所有事件带有的预置属性

以下预置属性，是Python SDK中所有事件（包括自动采集事件）都会带有的预置属性